/*
===============================================================================
GSOAP WINHTTP PLUGIN
-------------------------------------------------------------------------------

Allow gsoap clients and servers to direct all communications through the 
WinHttp API. This automatically provides all of the proxy and authentication 
features supported by the control panel 'Internet Options' dialog to the 
client. As these options are shared by IE, this means that "if IE works, 
gsoap works."
Need not any user interaction so it is possible to use this plugin in
windows services where the gsoapWinInet not works.

Project Home: http://code.google.com/p/gsoapwinhttp/

-------------------------------------------------------------------------------
Features
-------------------------------------------------------------------------------

 + gsoap plugin - extremely easy to use
 + complete support for:
     - HTTP/1.0 and HTTP/1.1
     - HTTPS (no extra libraries are required)
     - HTTP authentication
     - Proxy servers (simple, automatic discovery, etc)
     - Proxy authentication (basic, NTLM, etc)
 + authentication can be resolved by winhttp_set_proxy_params function.
 + HTTPS warnings (e.g. invalid HTTPS CA, CN or DATE) 
     resolved automatic by setting ignore options.
 + message size is limited only by available memory
 + connect, receive and send timeouts are used 
 + supports all SOAP_IO types (see limitations)
 + written completely in C, can be used in C, C++, and MFC projects
     without modification (anywhere that gsoap is used)
 + can be used in both MBCS and UNICODE projects
 + compiles cleanly at warning level 4 (if gsoap uses SOAP_SOCKET
     for the definition of sockets instead of int, it will also
     compile without win64 warnings).
 + all debug trace goes to the gsoap TEST.log file 
 + supports multiple threads (all plugin data is stored in the 
     soap structure - no static variables)

-------------------------------------------------------------------------------
Limitations
-------------------------------------------------------------------------------
 - DIME attachments are not supported
 - may internally buffer the entire outgoing message before sending
     (if the serialized message is larger then SOAP_BUFLEN, or if 
     SOAP_IO_CHUNK mode is being used then the entire message will 
     be buffered)

-------------------------------------------------------------------------------
Usage
-------------------------------------------------------------------------------

Add the gsoapWinHttp.h and gsoapWinHttp.cpp files to your project (if you 
have a C project, rename gsoapWinHttp.cpp to .c and use it as is). Ensure 
that you turn off precompiled headers for the .cpp file.

In your source, just after calling soap_init(), register this plugin with 
soap_register_plugin( soap, winhttp_plugin ). 

If your proxy need authentication just call the
     winhttp_set_proxy_params or winhttp_set_server_params

function.

For example:
     struct soap soap;
     soap_init( &soap );
     soap_register_plugin( &soap, winhttp_plugin );
     soap.connect_timeout = 5; // this will be used by winhttp too
     ...
     soap_done(&soap);

-------------------------------------------------------------------------------
Notes
-------------------------------------------------------------------------------

For extra control, you may also register this plugin using the 
soap_register_plugin_arg() function, and supply as the argument flags which 
you want to be passed to HttpOpenRequest. 

For example:
     struct soap soap;
     soap_init( &soap );
     soap_register_plugin_arg( &soap, winhttp_plugin,
         (void*) SECURITY_FLAG_IGNORE_CERT_DATE_INVALID );

See the MSDN documentation on HttpOpenRequest for details of available flags. 
The <winhttp.h> header file is required for the definitions of the flags. 
Some flags which may be useful are:


SECURITY_FLAG_IGNORE_CERT_CN_INVALID

     Disables Microsoft Win32 Internet function checking of SSL/PCT-
     based certificates that are returned from the server against 
     the host name given in the request. 

SECURITY_FLAG_IGNORE_CERT_DATE_INVALID

     Disables Win32 Internet function checking of SSL/PCT-based 
     certificates for proper validity dates.

This plugin uses the following callback functions and is not compatible 
with any other plugin that uses these functions.

     soap->fopen
     soap->fposthdr
     soap->fsend
     soap->frecv
     soap->fclose

-------------------------------------------------------------------------------
License 
-------------------------------------------------------------------------------

The licence text below is the boilerplate "MIT Licence" used from:
http://www.opensource.org/licenses/mit-license.php

Copyright (c) 2011, Daniel Rozsar

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

-------------------------------------------------------------------------------
Developers & changes
-------------------------------------------------------------------------------

23 June 2011: Daniel Rozsar (rozsar.daniel@gmail.com)
First release.

24 February 2012: Daniel Rozsar
The authentication was changed from pre authentication mode to
challenge-response scheme thanks for Tobias Germer

01 March 2012: Daniel Rozsar
The authentication setting mode was extend with a callback.
+ Can accept the user name and password for proxy and server as
  wide char with the winhttp_set_server_paramsw and winhttp_set_proxy_paramsw.
+ With winhttp_set_auth_callback can pass the authentication process to
  caller application. Suggested Tobias Germer.

*/

#ifndef INCLUDED_gsoapWinHttp_h
#define INCLUDED_gsoapWinHttp_h

#include <stdsoap2.h>

#ifdef __cplusplus
extern "C" {
#endif 

/* plugin registration */
extern int winhttp_plugin(struct soap *a_pSoap, struct soap_plugin *a_pPluginData, void *a_pUnused);

/* To set up user name and password. There are ANSI and wide char version.
   The dwProxyScheme can be one or more flag from these values:
      WINHTTP_AUTH_SCHEME_BASIC	
      WINHTTP_AUTH_SCHEME_NTLM	
      WINHTTP_AUTH_SCHEME_PASSPORT	
      WINHTTP_AUTH_SCHEME_DIGEST	
      WINHTTP_AUTH_SCHEME_NEGOTIATE	
	  or 0: if you want to select by plugin and proxy
*/
extern int winhttp_set_proxy_params(struct soap* a_pSoap, const char* a_pszProxyUser, const char* a_pszProxyPsw, DWORD dwProxyScheme);
extern int winhttp_set_proxy_paramsw(struct soap* a_pSoap, wchar_t* a_pszProxyUser, wchar_t* a_pszProxyPsw, DWORD dwProxyScheme);

/* To set up user name and password. There are ANSI and wide char version.
   The dwServerScheme can be one or more flag from these values:
      WINHTTP_AUTH_SCHEME_BASIC	
      WINHTTP_AUTH_SCHEME_NTLM	
      WINHTTP_AUTH_SCHEME_PASSPORT	
      WINHTTP_AUTH_SCHEME_DIGEST	
      WINHTTP_AUTH_SCHEME_NEGOTIATE
	  or 0: if you want to select by plugin and server
*/
extern int winhttp_set_server_params(struct soap* a_pSoap, const char* a_pszServerUser, const char* a_pszServerPsw, DWORD dwServerScheme);
extern int winhttp_set_server_paramsw(struct soap* a_pSoap, wchar_t* a_pszServerUser, wchar_t* a_pszServerPsw, DWORD dwServerScheme);

/*
Type of authentication callback function.

Parameter dwHttpStatus [in] can be:
	- HTTP_STATUS_DENIED: server authentication required or
	- HTTP_STATUS_PROXY_AUTH_REQ: proxy authentication required.
Parameter hRequest [in] handle of the opened request.
Return value:
	- SOAP_OK if the authentication was successful
	- any other by error.
*/
typedef int (*winhttp_auth_callback)(DWORD dwHttpStatus, HINTERNET hRequest);

/*
Set up a callback function for ask the caller to do the authentication.
If it was set than overrides all other authentication mode.
*/
extern void winhttp_set_auth_callback(struct soap *a_pSoap, winhttp_auth_callback pCallback);


#ifdef __cplusplus
}
#endif 

#endif // INCLUDED_gsoapWinHttp_h
